Skip to content

feat(vnext): prepare catalog epoch transitions#194

Merged
Light2Dark merged 1 commit into
dev-refactorfrom
codex/vnext-catalog-transition-hook
Jul 25, 2026
Merged

feat(vnext): prepare catalog epoch transitions#194
Light2Dark merged 1 commit into
dev-refactorfrom
codex/vnext-catalog-transition-hook

Conversation

@Light2Dark

@Light2Dark Light2Dark commented Jul 25, 2026

Copy link
Copy Markdown
Member

Part of #169. Follows #193.

  • Add a package-private synchronous epoch-transition hook so shared catalog work can retire before session revision listeners observe an accepted epoch.
  • Preserve deterministic prepare/commit/dispatch ordering for provider invalidations and higher response epochs.
  • Tighten provider cleanup and transition dispatch to an exact undefined contract, with fail-closed quarantine for invalid returns.
  • Dispose before inspecting invalid thenables, closing the hostile getter reentrancy window identified after feat(vnext): coordinate catalog epochs #193 merged.
  • Keep the no-hook and null-transition paths allocation-free and add a configured-hook storm benchmark.
  • Extend ADR 0005, type fixtures, lifecycle tests, and adversarial Promise/thenable coverage.

Summary by cubic

Adds a package-private, synchronous epoch-transition hook that runs after epoch install to retire catalog work before session listeners. Enforces exact-return contracts and fail-closed handling to harden reentrancy, cleanup, and poisoned-thenable edge cases; supports #169.

  • New Features

    • Added SqlCatalogEpochTransitionTarget that may return a dispatch closure or null; dispatch must return exactly undefined (sync only).
    • Preserved strict ordering: transition-prepare → revision-prepare → producer settle → transition-dispatch → revision-dispatch; reentrant dispatch queues behind current dispatch.
    • Snapshots the revision audience before transition; producers/aborts see prepared revisions; listeners see already-retired work.
    • Rejects non-function transition targets during coordinator creation (reason: "invalid-transition-target"); any thrown preparation, thrown dispatch, or non-undefined return disposes fail-closed and discards response decisions.
    • Drains detached Promise/thenable results for cleanup and transition returns after disposal, avoiding hostile getter reentrancy; no-hook and null-dispatch paths allocate nothing. Updated ADR 0005, added a configured-hook storm benchmark, and expanded adversarial tests.
  • Migration

    • Update SqlCatalogSubscriptionCleanup to be synchronous and return undefined only (no Promises or other return values).

Written for commit 9d7c9c3. Summary will update on new commits.

Review in cubic

@Light2Dark
Light2Dark requested a review from Copilot July 25, 2026 07:22
@github-actions

github-actions Bot commented Jul 25, 2026

Copy link
Copy Markdown

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 98.87% (🎯 91%) 438 / 443
🔵 Statements 98.29% (🎯 91%) 460 / 468
🔵 Functions 98.24% (🎯 90%) 56 / 57
🔵 Branches 97.32% (🎯 85%) 255 / 262
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
src/vnext/relation-catalog-epoch-coordinator.ts 98.29% 97.32% 98.24% 98.87% 239, 356, 415-416, 448, 562, 1023, 1067
src/vnext/relation-completion-types.ts 0% 0% 0% 0%
Generated in workflow #745 for commit 9d7c9c3 by the Vitest Coverage Report Action

@Light2Dark
Light2Dark marked this pull request as ready for review July 25, 2026 07:23

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a synchronous, package-owned “epoch transition” hook to the vnext catalog epoch coordinator so work can be retired deterministically between epoch installation and session revision listener dispatch, while tightening cleanup/dispatch contracts to exact undefined and hardening against hostile thenables.

Changes:

  • Introduces SqlCatalogEpochTransitionTarget and wires prepare/dispatch into the epoch coordinator with deterministic ordering and fail-closed quarantine on invalid/throwing behavior.
  • Tightens SqlCatalogSubscriptionCleanup to a synchronous exact-undefined return contract, with best-effort draining for accidental Promise/thenable returns after disposal.
  • Expands type fixtures, lifecycle/adversarial tests, adds a transition-hook storm benchmark, and updates ADR 0005 to document the new lifecycle/contract.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file
File Description
test/vnext-types/marimo-relation-completion.test-d.ts Extends d.ts fixtures to enforce exact-undefined cleanup and exact-undefined transition dispatch typing.
src/vnext/relation-completion-types.ts Tightens SqlCatalogSubscriptionCleanup to () => undefined for exact synchronous cleanup typing.
src/vnext/relation-catalog-epoch-coordinator.ts Implements transition prepare/dispatch hook, strict cleanup/dispatch return handling, and detached settlement draining.
src/vnext/tests/relation-catalog-epoch-coordinator.test.ts Adds ordering, reentrancy, and adversarial tests for transition hook and exact-return cleanup/dispatch behavior.
src/vnext/tests/relation-catalog-epoch-coordinator.bench.ts Adds benchmark coverage for configured (null-dispatch) transition hook under callback storms.
docs/adr/0005-parser-independent-relation-completion.md Documents the new transition hook lifecycle and the tightened exact-undefined cleanup contract.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 6 files

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread src/vnext/relation-catalog-epoch-coordinator.ts
@Light2Dark
Light2Dark force-pushed the codex/vnext-catalog-transition-hook branch from 23cc3f8 to 9d7c9c3 Compare July 25, 2026 07:34
@Light2Dark
Light2Dark merged commit 5ad22fd into dev-refactor Jul 25, 2026
9 checks passed
@Light2Dark
Light2Dark deleted the codex/vnext-catalog-transition-hook branch July 25, 2026 07:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants